home *** CD-ROM | disk | FTP | other *** search
/ Directorty Opus 5 - Magellan 2 / Opus 5 - Magellan 2.iso / Extras / opussdk / docs / images.doc < prev    next >
Text File  |  1996-09-05  |  11KB  |  343 lines
  1. TABLE OF CONTENTS
  2.  
  3. dopus5.library/CloseImage
  4. dopus5.library/CopyImage
  5. dopus5.library/FreeImageRemap
  6. dopus5.library/FreeRemapImage
  7. dopus5.library/GetImageAttrs
  8. dopus5.library/GetImagePalette
  9. dopus5.library/OpenImage
  10. dopus5.library/RemapImage
  11. dopus5.library/RenderImage
  12. dopus5.library/CloseImage                           dopus5.library/CloseImage
  13.  
  14.     NAME
  15.         CloseImage - close an image
  16.  
  17.     SYNOPSIS
  18.         CloseImage(image)
  19.                      A0
  20.  
  21.         void CloseImage(APTR);
  22.  
  23.     FUNCTION
  24.         Closes an image that was opened with OpenImage(). The usage count
  25.         of the image is decremented. When the count reaches 0 the image is
  26.         flushed from memory.
  27.  
  28.     INPUTS
  29.         image - image to close
  30.  
  31.     SEE ALSO
  32.         OpenImage()
  33.  
  34. dopus5.library/CopyImage                             dopus5.library/CopyImage
  35.  
  36.     NAME
  37.         CopyImage - copy an opened image
  38.  
  39.     SYNOPSIS
  40.         CopyImage(image)
  41.                     A0
  42.  
  43.         APTR CopyImage(APTR);
  44.  
  45.     FUNCTION
  46.         Returns another pointer to the supplied image.
  47.  
  48.     INPUTS
  49.         image - image to copy
  50.  
  51.     RESULT
  52.         Returns a new pointer to the image.
  53.  
  54.     SEE ALSO
  55.         OpenImage()
  56.  
  57. dopus5.library/FreeImageRemap                   dopus5.library/FreeImageRemap
  58.  
  59.     NAME
  60.         FreeImageRemap - free pens used to remap images
  61.  
  62.     SYNOPSIS
  63.         FreeImageRemap(remap)
  64.                          A0
  65.  
  66.         void FreeImageRemap(ImageRemap *);
  67.  
  68.     FUNCTION
  69.         Frees all the pens allocated with the supplied ImageRemap structure.
  70.         You should call this function after you have called FreeRemapImage()
  71.         or CloseImage() on the individual images.
  72.  
  73.     INPUTS
  74.         remap - ImageRemap structure to free
  75.  
  76.     SEE ALSO
  77.         RemapImage()
  78.  
  79. dopus5.library/FreeRemapImage                   dopus5.library/FreeRemapImage
  80.  
  81.     NAME
  82.         FreeRemapImage - free a remapped image
  83.  
  84.     SYNOPSIS
  85.         FreeRemapImage(image, remap)
  86.                         A0     A1
  87.  
  88.         void FreeRemapImage(APTR, ImageRemap *);
  89.  
  90.     FUNCTION
  91.         This function frees the remapped bitplanes allocated for an image
  92.         via the RemapImage() call.
  93.  
  94.     INPUTS
  95.         image - image to free remap bitplanes for
  96.         remap - ImageRemap structure
  97.  
  98.     RESULT
  99.         The remapped bitplanes are freed. This routine does not free any pens
  100.         that were allocated - these are released when you call FreeImageRemap().
  101.         Note that the image itself is not freed, only the remapped version of
  102.         it.
  103.  
  104.     SEE ALSO
  105.         RemapImage(), FreeImageRemap()
  106.  
  107. dopus5.library/GetImageAttrs                     dopus5.library/GetImageAttrs
  108.  
  109.     NAME
  110.         GetImageAttrs - get information about an image
  111.  
  112.     SYNOPSIS
  113.         GetImageAttrs(image, tags)
  114.                        A0     A1
  115.  
  116.         void GetImageAttrs(APTR, struct TagItem *);
  117.  
  118.     FUNCTION
  119.         This routine allows you to retrieve information about an image opened
  120.         with OpenImage().
  121.  
  122.     INPUTS
  123.         image - image to investigate
  124.         tags - control tags. The following tags are valid :
  125.  
  126.                IM_Width             - width of image
  127.                IM_Height            - height of image
  128.                IM_Depth             - number of bitplanes
  129.                IM_State             - 1 if the image has two frames, 0 if not
  130.  
  131.     RESULT
  132.         The requested information is stored in the ti_Data field of each of
  133.         the Tags passed in.
  134.  
  135.     SEE ALSO
  136.         OpenImage()
  137.  
  138. dopus5.library/GetImagePalette                 dopus5.library/GetImagePalette
  139.  
  140.     NAME
  141.         GetImagePalette - get pointer to image palette
  142.  
  143.     SYNOPSIS
  144.         GetImagePalette(image)
  145.                          A0
  146.  
  147.         ULONG *GetImagePalette(APTR);
  148.  
  149.     FUNCTION
  150.         This allows you to retrieve a pointer to the palette of the image.
  151.  
  152.     INPUTS
  153.         image - image you want the palette for
  154.  
  155.     RESULT
  156.         If the image has associated palette information (eg a brush), a
  157.         pointer to a longword palette table is returned. This palette table
  158.         is in LoadRGB32() format. If the image has no associated palette,
  159.         this routine returns NULL.
  160.  
  161.     SEE ALSO
  162.         OpenImage(), graphics.library/LoadRGB32()
  163.  
  164. dopus5.library/OpenImage                             dopus5.library/OpenImage
  165.  
  166.     NAME
  167.         OpenImage - read an image off disk
  168.  
  169.     SYNOPSIS
  170.         OpenImage(name, info)
  171.                    A0    A1
  172.  
  173.         APTR OpenImage(char *, OpenImageInfo *);
  174.  
  175.     FUNCTION
  176.         The primary purpose of this function is to read an image from a file
  177.         on disk. This routine supports ILBM brushes and pictures, animbrushes
  178.         and Amiga icons.
  179.  
  180.         This routine is also used to create an image handle to bitmap data
  181.         that you supply. This image handle can then be used with the image
  182.         remapping functions.
  183.  
  184.         This function caches images based on their full pathname. If two
  185.         copies of the same file are loaded, the first copy will be used to
  186.         save memory.
  187.  
  188.     INPUTS
  189.         name - name of image to load, or NULL if you are supplying a bitmap
  190.         info - if 'name' is NULL, this must point to an initialised
  191.                OpenImageInfo structure:
  192.  
  193.                     oi_ImageData - must point to the image data. This data
  194.                     does not need to be in chip memory.
  195.  
  196.                     oi_Palette - must point to a palette for the image, in
  197.                     LoadRGB32() format.
  198.  
  199.                     oi_Width - width of the image
  200.  
  201.                     oi_Height - height of the image
  202.  
  203.                     oi_Depth - number of image bitplanes
  204.  
  205.     RESULT
  206.         Returns an image handle if it succeeds. This handle is used in
  207.         subsequent calls to the image routines. This routine returns NULL if
  208.         it fails.
  209.  
  210.     SEE ALSO
  211.         CloseImage(), graphics.library/LoadRGB32()
  212.  
  213. dopus5.library/RemapImage                           dopus5.library/RemapImage
  214.  
  215.     NAME
  216.         RemapImage - remap an image
  217.  
  218.     SYNOPSIS
  219.         RemapImage(image, screen, remap)
  220.                     A0      A1      A2
  221.  
  222.         BOOL RemapImage(APTR, struct Screen *, ImageRemap *);
  223.  
  224.     FUNCTION
  225.         This function remaps an image to the colours of the specified screen.
  226.         It will allocate pens from the screen if necessary (and possible).
  227.  
  228.     INPUTS
  229.         image - image to remap (from OpenImage())
  230.         remap - ImageRemap structure. This structure must be initialised for
  231.                 the first call to RemapImage(). All fields must be set to
  232.                 NULL.
  233.  
  234.                 For the first and subsequent calls to this function, the
  235.                 ir_Flags field can be set with the following values :
  236.  
  237.                     IRF_REMAP_COL0      - remap colour 0 in the image
  238.                     IRF_PRECISION_EXACT - use best precision when pen matching
  239.                     IRF_PRECISION_ICON  - lower precision
  240.                     IRF_PRECISION_GUI   - lowest precision
  241.  
  242.                 You can use the one ImageRemap structure to remap multiple
  243.                 images, but only for the one screen. The ir_Flags field can be
  244.                 changed for every call to this function, but none of the
  245.                 other fields may be changed.
  246.                 
  247.     RESULT
  248.         This image returns TRUE if it was able to remap the image. Once the
  249.         image has been remapped, any call to RenderImage() to display it will
  250.         show the remapped version. Call FreeRemapImage() to free the remap
  251.         and return to the original image.
  252.  
  253.     SEE ALSO
  254.         OpenImage(), RenderImage(), FreeRemapImage(), FreeImageRemap()
  255.  
  256. dopus5.library/RenderImage                         dopus5.library/RenderImage
  257.  
  258.     NAME
  259.         RenderImage - display an image
  260.  
  261.     SYNOPSIS
  262.         RenderImage(rp, image, left, top, tags)
  263.                     A0    A1    D0   D1    A2
  264.  
  265.         short RenderImage(struct RastPort *, APTR, USHORT, USHORT,
  266.                           struct TagItem *);
  267.  
  268.     FUNCTION
  269.         This routine is used to render an image to a RastPort.
  270.  
  271.     INPUTS
  272.         rp - RastPort to render to
  273.         image - image to render
  274.         left - x position to render to
  275.         top - y position to render to
  276.         tags - control tags. The following tags are available :
  277.  
  278.             IM_State - 0 or 1 (default 0)
  279.  
  280.                 This tag controls which frame of the image is shown.
  281.                 Defaults to frame 0, but for two-frame images (eg icons or
  282.                 animbrushes) you can set this to 1.
  283.  
  284.             IM_Rectangle - struct Rectangle * (default not supplied)
  285.  
  286.                 This specifies a rectangle to display the image within. If
  287.                 you supply this tag, the image will be centered within this
  288.                 area. Use of this tag overrides the 'left' and 'top'
  289.                 parameters. 
  290.  
  291.             IM_ClipBoundary - integer (default 2)
  292.  
  293.                 This is used with the IM_Rectangle tag. If IM_Rectangle is
  294.                 specified, the image is clipped to the boundaries of the
  295.                 rectangle. The default operation is to leave a two pixel
  296.                 margin around the image (to allow room for a border). Using
  297.                 the IM_ClipBoundary tag you can adjust this margin (set to 0
  298.                 if you want no margin).
  299.  
  300.             IM_Mask - TRUE or FALSE (default FALSE)
  301.  
  302.                 If you set this tag to TRUE, the image will be masked when
  303.                 it is rendered. This has the effect of making colour 0
  304.                 transparent, and the existing background will show through
  305.                 the image.
  306.  
  307.             IM_Erase - integer (default not supplied)
  308.  
  309.                 This tag allows you to specify a pen value that is used to
  310.                 erase the background before the image is rendered. By
  311.                 default the background is not cleared.
  312.  
  313.             IM_NoDrawInvalid (default not supplied)
  314.  
  315.                 If you specify this tag, and also specify 1 for IM_State,
  316.                 then the call to RenderImage() will fail if the image has
  317.                 no secondary image. If this tag is not specified and you
  318.                 try to draw the second frame of an image that doesn't have
  319.                 one, it falls back to drawing the first frame.
  320.  
  321.             IM_NoIconRemap - TRUE or FALSE (default FALSE)
  322.  
  323.                 By default, an icon that is drawn with RenderImage() is
  324.                 "remapped". This is not a true colour remapping, but the
  325.                 third bitplane of an eight colour icon is shifted to the
  326.                 top bitplane of the display. This makes most normal eight
  327.                 colour icons work properly on screens of more than eight
  328.                 colours. However, it can cause problems with NewIcons
  329.                 icons. Specify TRUE with this tag to disable this remapping.
  330.  
  331.     RESULT
  332.         The image is rendered. If you specified IM_NoDrawInvalid and you
  333.         tried to draw an image that didn't exist, this routine returns FALSE.
  334.         Otherwise it returns TRUE.
  335.  
  336.     NOTES
  337.         If the image has been remapped with RemapImage(), the remapped image
  338.         will be automatically drawn by this routine.
  339.  
  340.     SEE ALSO
  341.         OpenImage(), RemapImage()
  342.  
  343.